第三部分：参数篇
5. pegasus 命令参数详解
本章节详细列出了 pegasus 命令行工具在各个核心阶段（导入、量化、推理、导出）所支持的参数。
5.1 模型导入 (Import)
目标：此为工具链的第一步，旨在将一个由主流框架（如 TensorFlow、ONNX、Caffe）训练生成的模型，解析并转换为 taNNTC 工具链专用的中间表示 (IR) 格式。
输入：原始模型文件（例如 .onnx、.pb、.tflite 文件）。
输出：一个 .json 文件（描述网络结构）和一个 .data 文件（存储网络权重）。这对文件是后续所有操作的基础。
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
--model | 待导入的源模型文件路径 | str | — | --model yolo11s.onnx |
--weights | 源模型权重文件（部分框架需要，如 Caffe/Darknet） | str | — | --weights model.caffemodel |
--inputs | 模型输入节点名（空格分隔多个） | str list | 框架可自动识别时可省略 | --inputs images |
--input-size-list | 各输入张量形状，输入间用 # 分隔 | str | 自动推断（支持时） | --input-size-list 1,3,640,640 |
--outputs | 模型输出节点名（空格分隔多个） | str list | 自动识别（支持时） | --outputs out0 out1 out2 |
--size-with-batch | input-size-list 是否含 batch 维 | True/False（可多输入用 # 对应） | False | --size-with-batch False |
--input-dtype-list | 各输入数据类型 | float/int8/uint8/int16/… | float | --input-dtype-list float |
--mean-values | 输入均值 | float[,float...] | — | --mean-values 0.0,0.0,0.0 |
--std-values | 输入标准差 | float[,float...] | — | --std-values 255.0,255.0,255.0 |
--predef-file | 预定义 .npz（占位符/阶段开关等） | str | — | --predef-file flags.npz |
--subgraphs | 指定子图的输入/输出列表 | str | — | --subgraphs in1#out1;in2#out2 |
--output-model | 转换后网络结构 .json 输出路径 | str | 同目录同名 .json | --output-model y11.json |
--output-data | 转换后权重 .data 输出路径 | str | 同目录同名 .data | --output-data y11.data |
--config | 导入配置文件（部分框架专用） | json | — | --config import_cfg.json |
5.2 模型预处理配置文件生成 (Generate)
目标：此模块用于基于已导入的模型结构（.json 文件），自动生成预处理和后处理配置文件的模板（.yml 文件），简化配置过程。
输入：.json 文件。
输出：.yml 配置文件。
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
inputmeta | 子命令：指定生成输入端预处理文件 | — | — | pegasus generate inputmeta ... |
postprocess-file | 子命令：指定生成输出端后处理文件 | — | — | pegasus generate postprocess-file ... |
--model | 输入的 .json 模型结构文件路径 | str | — | --model yolo11s.json |
--input-meta-output | 指定输出的 inputmeta.yml 文件路径 | str | — | --input-meta-output meta.yml |
--postprocess-file-output | 指定输出的 postprocess_file.yml 文件路径 | str | — | --postprocess-file-output post.yml |
5.2.1 *_inputmeta.yml 前处理配置文件内容详解
此文件用于配置模型输入端的预处理。
-
常见配置：
mean、scale：设置归一化的均值和缩放系数。reverse_channel：BGR 与 RGB 通道反转开关。工具链将图片解码后按 RGB 顺序输入网络。如果目标网络默认的 channel 顺序是 BGR，则此处需要将此项设为true。若不需要反转通道，则设为false。
-
高级用法（指定输入格式）：如果希望模型直接接收
RGB_PACKED或NV12等特定硬件格式的数据，并让 NPU 执行预处理，需要修改：add_preproc_node: true
preproc_type: IMAGE_NV12 # (或其他格式)
5.2.2 *_postprocess_file.yml 后处理配置文件内容详解
此文件用于配置模型输出端的后处理。
-
常见用法（强制输出为 Float32）：默认情况下，模型输出的数据类型与量化类型一致。如果希望无论量化类型是什么，最终输出都是 Float32，需要对每个输出层进行如下配置：
postprocess:
app_postprocs: # 该部分配置会影响最终导出的模型
- lid: output_0 # 替换为您的输出层名称
postproc_params:
add_postproc_node: true
force_float32: true # 强制输出为 float32
# 如果有多个输出层，在此继续添加
- lid: output_1
postproc_params:
# ...
5.3 模型量化 (Quantize)
目标：此为关键的优化步骤，旨在通过降低模型的数据精度（例如从 FP32 转换为 INT8），来减小模型体积、降低内存占用，并利用 NPU 的定点运算单元实现显著的推理加速。
输入：上一阶段生成的 .json 和 .data 文件，以及一个用于校准的样本数据集。
输出：一个 .quantize 文件，其中包含了每一层的量化参数（如缩放因子、零点等）。
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
--model | 待量化的 .json | str | — | --model y11.json |
--model-data | 待量化的 .data | str | — | --model-data y11.data |
--dataset | 量化数据集列表文件（每行一张图片路径） | str | — | --dataset dataset.txt |
--with-input-meta | 输入元数据 .yml（预处理/路径等） | str | — | --with-input-meta inputmeta.yml |
--batch-size | 校准批大小 | int | 由输入元数据推断 | --batch-size 1 |
--iterations | 校准批次数 | int | 1 | --iterations 500 |
--device | 量化计算设备 | GPU/CPU | GPU | --device GPU |
--quantizer | 量化方案（定点/通道/分组等） | asymmetric_affine / perchannel_symmetric_affine / … | asymmetric_affine | --quantizer perchannel_symmetric_affine |
--qtype | 目标精度类型 | uint8 / int8 / int16 / bfloat16 / float16 / … | uint8 | --qtype uint8 |
--algorithm | 校准算法 | normal / kl_divergence / moving_average / auto | normal | --algorithm kl_divergence |
--moving-average-weight | 滑动平均系数（选 moving_average 时有效） | float | 0.01 | --moving-average-weight 0.01 |
--divergence-first-quantize-bits | KL 直方图桶指数 m（桶数=2^m） | int | 11 | --divergence-first-quantize-bits 11 |
--compute-entropy | 计算各层量化熵以评估敏感度 | flag | 关闭 | --compute-entropy |
--MLE | 最小化层误差优化（微调缩放） | flag | 关闭 | --MLE |
--group-size | 分组量化组大小（16 的倍数） | int | — | --group-size 32 |
--model-quantize | .quantize 文件路径（重用/保存） | str | 同名生成 | --model-quantize y11.quantize |
--hybrid | 启用混合量化（自动/规则混合） | flag | 关闭 | --hybrid |
--rebuild | 重新量化（覆盖旧 .quantize） | flag | 关闭 | --rebuild |
--rebuild-all | 强制全层量化（实验） | flag | 关闭 | --rebuild-all |
5.4 模型推理 (Inference)
目标：此模块用于在 开发主机（PC/服务器） 上模拟模型的推理过程，主要用于功能验证和精度评估。您可以在部署到硬件之前，用它来快速验证原始浮点模型的正确性，或评估量化后模型的精度损失情况。
输入：.json 和 .data 文件，（若评估量化模型）还需 .quantize 文件。
输出：模型的推理结果，可用于与基准值 (Golden) 进行比对。
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
--model | 推理用 .json | str | — | --model y11.json |
--model-data | 推理用 .data | str | — | --model-data y11.data |
--model-quantize | 推理用 .quantize（选择量化推理时） | str | — | --model-quantize y11.quantize |
--with-input-meta | 输入元数据 .yml | str | — | --with-input-meta inputmeta.yml |
--dtype | 推理精度 | float32 / quantized | float32 | --dtype quantized |
--batch-size | 推理批大小 | int | 由输入元数据推断 | --batch-size 1 |
--iterations | 推理批次数 | int | 1 | --iterations 100 |
--device | 推理计算设备 | GPU/CPU | GPU | --device GPU |
--postprocess | 内置后处理任务 | print_topn / dump_result / classification_validate / detection_validate / … | classification_classic | --postprocess detection_validate |
--postprocess-file | 自定义后处理 .yml | str | — | --postprocess-file post.yml |
--output-dir | 推理结果输出目录 | str | 当前目录/控制台 | --output-dir outputs/ |
5.5 模型导出 (Export)
目标：此为工具链的最后一步，旨在将中间表示 (IR) 和量化结果，编译并打包成一个专为目标 NPU 硬件优化、可直接部署执行的最终产物。
输入：.json、.data 文件以及（若为量化模型）.quantize 文件。
输出：一个或多个可直接在板端运行的文件，最核心的是统一的二进制图文件（例如 .nb）。
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
--model | 导出用 .json（含量化结构时可指向 *.quantize.json） | str | — | --model y11.json |
--model-data | 导出用 .data | str | — | --model-data y11.data |
--model-quantize | 量化信息 .quantize（导出量化推理代码时） | str | — | --model-quantize y11.quantize |
--with-input-meta | 输入元数据 .yml（可融合预处理节点） | str | — | --with-input-meta inputmeta.yml |
--postprocess-file | 后处理配置 .yml（导出侧集成） | str | — | --postprocess-file post.yml |
--output-path | 输出工程目录与前缀 | str | 当前目录 | --output-path ./export_yolo11s/y11 |
--optimize | 导出优化策略/目标硬件配置 | None / default / <hw_profile> | default | --optimize default |
--dtype | 导出应用计算精度 | float32 / float16 / quantized | float16 | --dtype quantized |
--save-fused-graph | 导出融合后模型 .json（调试） | flag | 关闭 | --save-fused-graph |
--pack-nbg-unify | 生成统一二进制图（.nb）应用 | flag | 关闭 | --pack-nbg-unify |
--viv-sdk | VIV SDK cmdtools 路径（配合打包二进制图） | str | — | --viv-sdk /opt/viv/cmdtools |
--build-platform | 工程构建方式 | make | make | --build-platform make |
--target-ide-project | 目标平台 | linux64 / win32 | linux64 | --target-ide-project linux64 |
--batch-size | 导出支持的最大 batch | int | 由输入元数据推断 | --batch-size 1 |
--force-remove-permute | 移除首尾 Permute（改变 IO 布局） | flag | 关闭 | --force-remove-permute |